Naming Conventions

The IRI of an entity has two parts: the namespace and the local identifier. Within one RDF document the namespace might be associated by a shorter prefix. For instance the namespace IRI http://www.w3.org/2002/07/owl# is commonly associated with the prefix owl: and one can write owl:Class instead of the full IRI http://www.w3.org/2002/07/owl#Class.

Namespaces

Within this specification, the following namespace prefix bindings are used:

Indication of Requirement Levels

Within this document the definitions of MUST, SHOULD and MAY are used as defined in [[!rfc2119]].

Diagram Notation

This document MAY use the Unified Modeling Language [[UML]] to illustrate some concepts and visualize RDF graphs. These diagrams are non-normative and SHOULD not be interpreted in the strict interpretation specified by the UML specification.

Number Formatting

Within this document, decimal numbers will use a dot "." as the decimal mark.

Explicit Definition of Dimensions and Measures

The API MUST provide a method to describe the structure of the data cube by explicitly defining one or more measures and, optionally, one or more dimensions.

	ex:intensityMeasure
		a                           adf-dc:RatioScale ,       # MAY
									adf-dc:Measure ,
									qb:ComponentSpecification ;
		adf-dc:componentDataType    xsd:int ;
		qb:measure                  «af-x:intensity» .        # the measure property
							

	ex:sampleIndexDimension
			a                         adf-dc:RatioScale ,           # MAY
									  adf-dc:Dimension ,
									  qb:ComponentSpecification ;
			adf-dc:componentDataType  afs-qudt:ArbitraryUnitValue ;
			adf-dc:orderedBy          adf-dc:nativeOrder ;          # SHOULD
			qb:dimension              «af-x:index» ;
			qb:order                  "1"^^xsd:long .               # SHOULD
							

ex:UseCaseDataSet
        a             qb:DataSet ;
        rdfs:label    "Data Cube for LC/MS use case" ;          # SHOULD
        dct:title     "Data Cube for LC/MS use case" ;          # SHOULD
        qb:structure  ex:UseCaseDSD .
ex:UseCaseDSD
        a               qb:DataStructureDefinition ;
        qb:component    ex:sampleIndexDimension ,
                        ex:massPerChargeDimension ,
                        ex:retensionTimeDimension ,
                        ex:intensityMeasure  .
                

Reference to a Data Structure Definition

The structure of a data cube is expressed by a data structure definition (DSD) qb:DataStructureDefinition which defines the dimensions and measures of the data cube. There MUST be a way to reuse an explicitly created DSD, since many data cubes share a common structure. There MAY be a way to reuse an implicitly created DSD. A DSD is created implicitly for every created DataCube that does not reuse an existing DSD. Thus, the API MUST provide a method to specify the structure of a data cube at creation time by reference to a IRI of a predefined DSD. The detailed requirements of the method are described next. The method for creation of a reusable DSD is described afterwards.

ex:UseCaseDataSet
a             qb:DataSet ;
rdfs:label    "Data Cube for LC/MS use case" ; # MAY
dct:title     "Data Cube for LC/MS use case" ; # MAY
qb:structure  ex:UseCaseDSD .                  # MUST reference to the reused DSD
				

Parameters

The API method for definition of a data structure definition (DSD) MUST provide parameters for creation of measures and dimensions as listed above. Furthermore, the following parameters MUST be provided:

• The API MUST provide a parameter for specification of the IRI of the DSD.

• It SHOULD be possible to define at least one label for the DSD.

• Exactly one size for each dimension component that is specified through an integer and defines the maximal number of entries in the corresponding dimension.

Persistence in ADF Data Description

The API method for definition of a DSD MUST persist the description of the DSD in ADF-TS as follows:

ex:UseCaseDSD                                       # MUST: IRI of the DSD
    a               qb:DataStructureDefinition ;    # MUST
    rdfs:label      "LC/MS use case DSD" ;          # SHOULD: a label for the DSD
    qb:component    ex:sampleIndexDimension ,
                    ex:massPerChargeDimension ,
                    ex:retensionTimeDimension ,
                    ex:intensityMeasure  .
                

Dimension Selections

The API MUST provide methods for specifying a dimension selection adf-dc:DimensionSelection, i.e. a selection on a dimension component.

Measure Selections

The API MUST provide methods for specifying a measure selection adf-dc:MeasureSelection, i.e. a selection on a measure component. The scale type of the measure component determines which selections are possible.

Convenience Methods

The API SHOULD provide a convenience method to select the complete content of the data cube.

Principle

Writing into a data cube SHOULD be based on the following principle: A source data selection is written to a target data selection. The values of the source data selection are read in the order of the dimensions and written in the same way into the target data selection. The following figure illustrates this principle: On a 3x5 data cube, a 3x2 data selection (marked in green) is created. This source data selection is written to a 2x3 data selection (marked in read) on the target 3x3 data cube.

Parameters

The API method for writing data into an data cube MUST provide the following parameters:

• A parameter for the specifying the data selection of the data cube the data is written to.
• A parameter for the specifying the data selection that contains the data that should be written to the data cube.
• If the target and source data cubes have different measures, the API MUST provide a parameter for specifying the injective mapping from source to target measures.
• The API method MUST provide a parameter to specify data that should be written to the data cube MAY be in form of an n-dimensional array.

• The API MAY provide a parameter to specify how to handle cases where the target data selection already contains values (e.g., overwriting or keeping existing values).

Reading the Complete Data from a Data Cube

The ADF-DC API MUST provide a method to read the complete data from of a data cube.

Reading Data from a Data Cube by a Data Selection

The API MUST provide a method for reading data from a data cube by specifying a data selection.

Describing Dimensions

Regarding dimension components there are some HDF5 specifics that MAY be provided by the API. These are listed in the following subsections.